home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / asmutil / asm_n_z.zip / SIT.DOC < prev    next >
Text File  |  1989-05-26  |  13KB  |  394 lines
  1. ===== WHAT IS "SIT"?
  2.  
  3.   SIT is a utility program for creating, modifying or deleting
  4. strings in the MS-DOS environment.  It overcomes some
  5. limitations of the intrinsic MS-DOS SET command, and provides
  6. additional features as well.
  7.  
  8.  
  9. ===== OKAY, SWELL.  WHAT IS "SET"??
  10.  
  11.   MS-DOS has an intrinsic command called SET for creating and
  12. deleting environment strings.  ("Intrinsic" means that the
  13. command is built into the DOS command interpreter program
  14. COMMAND.COM, rather than existing as a separate program file.)
  15.  
  16.   However, there's a problem with SET -- it only works on the
  17. _current_ copy of the environment strings.
  18.  
  19.   When you first boot up a PC with MS-DOS, a _master_copy_ of
  20. COMMAND.COM is loaded into memory, and this copy creates a
  21. _master_environment_ block.  Each time you run a program under
  22. MS-DOS, COMMAND.COM makes a _new_copy_ of the environment
  23. strings (in a separate memory block) that is used by the program
  24. you run.
  25.  
  26.   SET modifies the _current_ copy of the environment.  When
  27. you're sitting at the command prompt C>, the "current" copy _is_
  28. the MASTER copy.
  29.  
  30.   However, when you run a .BAT file, COMMAND.COM creates a
  31. "working" copy of the environment for use by that .BAT file --
  32. and if the .BAT file has a SET command in it, it's the WORKING
  33. copy that gets modified.
  34.  
  35.   That's great if the environment string you're creating or
  36. modifying is used WITHIN the .BAT file, but if you want the new
  37. environment value to be "permanent" (that is, you want your
  38. changes to survive after the .BAT file terminates), you're out
  39. of luck -- because COMMAND.COM discards the WORKING copy of the
  40. environment strings when the .BAT file completes... and the
  41. MASTER copy doesn't have the changes in it!
  42.  
  43.  
  44.   SET is also pretty simple-minded about its syntax.
  45.  
  46.   If you type the command
  47.  
  48.       SET VOOTIE=SOMETHING
  49.  
  50. and then examine your environment (just type SET without
  51. parameters), you'll see that you've got an entry that says the
  52. variable "VOOTIE" is equal to the value "SOMETHING".  Enter
  53.  
  54.       SET VOOTIE=
  55.  
  56. and that entry will be cleared out of your environment.
  57.  
  58.   Now, if you throw in an extra space, _you_ might not notice,
  59. but SET thinks you're talking about something entirely different!
  60.  
  61.       SET VOOTIE = SOMETHING
  62.  
  63. puts a variable called "VOOTIE " (note the trailing space!)
  64. equal to the value " SOMETHING" (note the _leading_ space!)
  65.  
  66.   As far as MS-DOS is concerned, the environment variables
  67. "VOOTIE" and "VOOTIE " are two completely different, unrelated
  68. variable names (and may have completely different values as
  69. well).  This can easily lead to confused programmers,
  70. particularly when you've been debugging since half past
  71. midnight...
  72.  
  73.   SIT trims the trailing spaces (between the variable name and
  74. the "=" sign), so SET VOOTIE=SOMETHING and SET VOOTIE =SOMETHING
  75. both apply to the environment variable VOOTIE.  However, (since
  76. you may _want_ to embed spaces within the _value_) SIT treats
  77. everything _after_ the "=" sign as significant:
  78.  
  79.           SET VOOTIE = SOMETHING    is not the same as
  80.       SET VOOTIE =SOMETHING
  81.  
  82.             --
  83. ===== WHY IS "SIT" BETTER THAN "SET"?
  84.  
  85.   SIT lets you do everything SET does, but it does it to the
  86. MASTER copy of the environment strings.
  87.  
  88.   SIT also trims trailing spaces off the names of environment
  89. variables, so you don't accidentally create a new variable that
  90. isn't what you thought it was. (See above.)
  91.  
  92.   SIT provides three new syntax forms that allow you to
  93.  
  94.       -- APPEND a string to the end of an existing value
  95.       -- PREPEND a string to the beginning of an existing value
  96.       -- REMOVE a substring from within an existing value
  97.  
  98.   Finally, SIT accepts one or more environment-variable
  99. assignments from standard input.  This lets you redirect a text
  100. file into SIT to make several assignments at once, or "pipe" the
  101. output of a program into SIT.  For example, in my AUTOEXEC.BAT
  102. file, I pipe the output of a program that reports the current
  103. system date and time (in a special format) into SIT to set a
  104. variable
  105.  
  106.       DATESTAMP=yymmdd
  107.  
  108. that is used by my program MAKE tool to automatically include
  109. the date a program was assembled or compiled into the program
  110. itself.  This helps to keep track of versions and changes.
  111.  
  112.  
  113. ===== WHY DO YOU CALL IT "SIT"?
  114.  
  115.   'Cuz I feel like it.  However,
  116.  
  117.   1) "SIT" is pretty close to "SET", which is good since they
  118.       do the same kind of work.
  119.  
  120.   2) "sit" is a Latin verb, a form of the verb "esse" (to be).
  121.       (Pluperfect imperative, I think.  Mrs. Ferguson, where
  122.        the heck are you when I _need_ you???)
  123.  
  124.      "sit" means roughly "Let it be" or "Make it so" (with
  125.        apologies to Capt. J.-L. Picard) which is a pretty good
  126.        match to the command "set" (x equal to y).
  127.  
  128.      For example, the motto of the University of Washington is
  129.        LUX SIT  ("Let there be light").  (The rumor that "Lux,
  130.        sit!" is what the Husky cheerleaders say to the mascot
  131.        is, of course, completely unfounded...)
  132.  
  133.  
  134.  
  135. ===== FINE, YOU'RE A NERD IN THREE LANGUAGES.  HOW DO I USE IT?
  136.  
  137. SIT <variable>=<value>
  138.  
  139.     For example,
  140.  
  141.         SIT path=c:\;c:\bin
  142.  
  143.     will either create the variable PATH (if it doesn't
  144.     already exist in the master environment) and assign
  145.     it the value "c:\;c:\bin", or (if it already exists)
  146.     change it from its previous value to "c:\;c:\bin".
  147.  
  148.     Notice that the name of the VARIABLE is forced to
  149.     upper-case ("PATH" rather than "path")... but the
  150.     VALUE keeps the case of the letters you type
  151.     ("c:\;c:\bin" rather than "C:\;C:\BIN")
  152.  
  153.     Since SIT trims the trailing spaces off the variable
  154.     name (which SET doesn't do),
  155.  
  156.         SIT   path    =c:\;c:\bin
  157.  
  158.     does the same thing as the first version.  HOWEVER,
  159.     spaces AFTER the equals sign are significant!
  160.  
  161.         SIT path1  =  c:\; c:\bin
  162.  
  163.     sets the variable PATH1 to the value "  c:\; c:\bin"
  164.     (notice the embedded spaces!)
  165.  
  166.  
  167. SIT <variable>
  168.  
  169.     Reports the current value of VARIABLE, if it exists
  170.     in the master environment.
  171.  
  172.  
  173. SIT <variable>=
  174.  
  175.         Clears VARIABLE out of the master environment if it
  176.     exists.
  177.  
  178.     Notice that the "=" must be the very last thing on the
  179.     command line.  If you follow the "=" with one or more
  180.     spaces, you are setting the value of VARIABLE to "  ".
  181.  
  182.  
  183.  
  184. (Enhanced syntax for SIT)--
  185.  
  186.  
  187. SIT <variable>-=<value>
  188.  
  189.     Removes a substring from an existing value.  If
  190.     VARIABLE exists in the master environment, SIT searches
  191.     its value for the leftmost substring matching <value>
  192.     and chops it out of the value.    For example, if you
  193.  
  194.             SIT ITEM =HUBBA HUBBA
  195.             SIT ITEM -=UBB
  196.  
  197.     then the new value of ITEM is "HA HUBBA" (the second
  198.     command removed the LEFTMOST letters "UBB").
  199.  
  200.     If VARIABLE does not exist, or if <value> is not a
  201.     substring of an existing value, nothing happens.
  202.  
  203.     If the substring removed is the _entire_ existing value,
  204.     SIT eliminates VARIABLE from the environment entirely.
  205.     That is, it treats VARIABLE as though you had said
  206.  
  207.             SIT VARIABLE=
  208.  
  209.     If SIT did not remove the variable, it would leave it in
  210.     the environment but with an empty value -- something that
  211.     could be useful, but isn't the way SET works, so we won't
  212.     work that way either.
  213.  
  214.  
  215.  
  216. SIT <variable>+=<value>
  217.  
  218.     Appends a substring to the END of an existing
  219.     variable, or creates a new variable with the <value>.
  220.  
  221.     For example,
  222.  
  223.         SIT ITEM =HUBBA
  224.         SIT ITEM +=DUBBA
  225.  
  226.     then the new value of ITEM is "HUBBADUBBA" (notice,
  227.     no space!  If you wanted a space, you should have
  228.     said
  229.  
  230.         SIT ITEM += DUBBA
  231.  
  232.     right?)
  233.  
  234.     If VARIABLE doesn't yet exist, SIT += does the same
  235.     thing that SIT = does:
  236.  
  237.         SIT NEWVARIABLE +=BYE BYE BLACKBIRD
  238.  
  239.     (the value of NEWVARIABLE is "BYE BYE BLACKBIRD").
  240.  
  241.  
  242.  
  243. SIT <variable>&=<value>
  244.  
  245.     &= works like +=, except that it PREPENDS the substring
  246.     <value> to the BEGINNING of an existing value. Example:
  247.  
  248.     SIT ITEM=HUBBA          (value is "HUBBA")
  249.     SIT ITEM+=DUBBA        (value is "HUBBADUBBA")
  250.     SIT ITEM-=HUBBA        (value is "DUBBA")
  251.     SIT ITEM&=RUBBA     (value is "RUBBADUBBA")
  252.  
  253.     This is handy for doing things like adjusting your
  254.     PATH.  For example,
  255.  
  256.     SIT PATH &=C:\L